home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / DJGPP / QDDVX102.ZIP / contrib / dvx / docs / help.doc < prev    next >
Text File  |  1993-07-15  |  21KB  |  607 lines
  1.  
  2. DESQview/X Help Programming Reference
  3. -------------------------------------
  4. The DESQview/X Help System is a general mechanism for providing 
  5. on-line help services to applications.  The basic metaphor is a 
  6. wire bound flip reference with topics organized into sections.  
  7. This widely recognized metaphor provides more information than a 
  8. reference card in a more concise presentation than a user manual.
  9.  
  10. The help notebook contains tabs along its lower edge that allow a 
  11. user to turn to the beginning of a particular section, and 
  12. navigation buttons down the right hand side. The notebook 
  13. displays as much of a topic as possible and lists the number of 
  14. pages in the topic as well as the topic number along its lower 
  15. edge. The text of a topic may be accented by changes in font and 
  16. color, and may contain pictures (or icons). In addition, the text 
  17. may contain hypertext links whereupon if a user clicks with the 
  18. mouse on a word(s), the notebook automatically jumps to a new 
  19. topic. This jump text is usually highlighted in a different color 
  20. to distinguish it from regular text. The buttons to the right 
  21. allow a user to backtrack through a notebook (after clicking on 
  22. jump text and/or section tabs), display the previous or next 
  23. topic, display the previous or next page of a topic (paging up 
  24. and down) as well as being able to close the notebook (exit).
  25.  
  26.  
  27. Help System Components
  28. ----------------------
  29. The DESQview/X Help System consists of the following 3 
  30. components:
  31.  
  32. A Help File      This is a single file that contains all of the 
  33.                  notebook's text and pictures, instructions for 
  34.                  moving around the notebook (jump instructions) 
  35.                  as well as specifying the section tabs, colors, 
  36.                  etc.
  37.  
  38. The DESQview/X   This is the application that reads the help 
  39. Help Engine      file, creates the notebook on the display screen 
  40.                  and responds to user input.
  41.  
  42. Help Interface   These routines are used by an application to 
  43. Routines         instruct the Help engine to display help. They 
  44.                  transparently handle the starting of the Help 
  45.                  engine and the communication that occurs between 
  46.                  the Help engine and the application.  In 
  47.                  addition, a stand alone version of these 
  48.                  routines are provided in the form of the 
  49.                  DISPHELP program which can be used from the 
  50.                  command line or in a .DVP file to display a help 
  51.                  notebook.
  52.  
  53. This chapter first discusses how to create a Help file and is 
  54. followed by details on using the help interface routines and the 
  55. DISPHELP program.
  56.  
  57.  
  58. Help File Structure
  59. -------------------
  60. It is recommended that help files for applications follow this 
  61. structure:
  62.  
  63. Contents      A section containing the contents of the notebook 
  64.               with jumps into the notebook.
  65.  
  66. Overview      A general overview of the application and how to 
  67.               navigate within it.
  68.  
  69. Commands      Help for all of the commands available in the 
  70.               application.
  71.  
  72. Dialogs       Help for all of the dialogs that the application 
  73.               displays.
  74.  
  75. Errors        Help for the individual error messages the 
  76.               application issues.
  77.  
  78. Naturally, you may wish to extend or customize this suggestion to 
  79. your own particular needs.
  80.  
  81. The files for this structure would probably be listed in this 
  82. order (when presented to HELPLIB.EXE in order to create the help 
  83. file):
  84.  
  85. frcover         (Front cover)
  86. contents        (Notebook contents)
  87. overview        (Overview contents)
  88. oview1          (Overview first topic)
  89. oview2          (Overview second topic)
  90. :
  91. commands        (Commands contents)
  92. command1        (First command topic)
  93. command2        (Second command topic)
  94. :
  95. dialogs         (Dialogs contents)
  96. dialog1         (First dialog topic)
  97. dialog2         (Second dialog topic)
  98. :
  99. errors          (Error contents)
  100. error1          (First error topic)
  101. error2          (Second error topic)
  102. :
  103. bkcover         (Back cover)
  104. include1        (Included topics)
  105. include2
  106. :
  107. xpm1            (Picture files)
  108. xpm2
  109.  
  110. HELPLIB.EXE
  111. -----------
  112. A utility program, HELPLIB.EXE is provided to create and update 
  113. help files. The command line options are as follows:
  114.  
  115. HELPLIB [libname | @responsefile]
  116.  
  117. libname, the name of an existing library on which to perform 
  118. maintenance.
  119.  
  120. responsefile, the name of a file to read commands from as though 
  121. they were entered interactively.
  122.  
  123. If no response file is specified (i.e. no command line parameter 
  124. or only a library name), then HELPLIB.EXE runs interactively with 
  125. the following commands available:
  126.  
  127. Add      Add a file to the end of the help file
  128.  
  129. Burst    Burst a help file into its constituent files
  130.  
  131. Change   Rename the name of the help file
  132.  
  133. Dir      List the files added to the help file
  134.  
  135. Erase    Remove a file from the help file
  136.  
  137. Get      Copy a constituent file out of the help file
  138.  
  139. Insert   Insert a file into the help file
  140.  
  141. Make     Create a new help file
  142.  
  143. Replace  Replace a constituent file in the help file
  144.  
  145. Use      Starting using a different help file
  146.  
  147. Quit     Return to DOS
  148.  
  149. Note that commands may be entered by first letter only.
  150.  
  151. A response file contains text exactly as it would be entered 
  152. interactively with one response per line. An example response 
  153. file would be:
  154.  
  155. m                       (Make 
  156. a new file)
  157. newfile.hlp             (name of file)
  158. frcover                 (front cover)
  159. contents                (topic files)
  160. overview
  161. commands
  162. command1
  163. command2
  164. dialogs
  165. errors
  166. bkcover                 (back cover)
  167. include                 (include files)
  168. xpmfile.xpm             (picture files)
  169. exit                    (exit signals end of m command)
  170. q                       (Quit)
  171.  
  172. A good idea is to create a batch file that uses a response file 
  173. like the one shown above:
  174.  
  175. MAKEHELP.BAT:
  176. del newfile.hlp
  177. helplib @newfile.rsp
  178.  
  179. This ensures that the topics are merged into the help file in the 
  180. correct order.
  181.  
  182. Example
  183. -------
  184.  
  185. We shall now build an example help file. The X11 Toolkit diskettes 
  186. contain the appropriate help example files.
  187.  
  188. First, open a DOS Window and change to the correct directory:
  189.  
  190. Type CD \DJGPP\CONTRIB\DVX\QDECK\HELP\EXAMPLE and press Enter .
  191.  
  192. Create the new help file:
  193.  
  194. Type HELPLIB @EXAMPLE.RSP and press Enter.
  195.  
  196. Now copy the new help file to the help directory and display it:
  197.  
  198. Type COPY EXAMPLE.HLP \DVX\HELP and press Enter.
  199.  
  200. Type DISPHELP -F EXAMPLE.HLP and press Enter.
  201.  
  202. It is recommended that you examine the response file EXAMPLE.RSP 
  203. as well as the topic files it uses as an example of writing and 
  204. using topic files.
  205.  
  206.  
  207. DESQview/X Help Interface
  208. -------------------------
  209. When you have created your DESQview/X Help .HLP file using 
  210. HELPLIB, your program can request that Help display a help 
  211. notebook at a particular topic. (It should be noted that your 
  212. program need not be an X client - the help interface routines do 
  213. not rely on the X Window System.)
  214.  
  215. To do this requires the use of two files - HELP.H and the 
  216. DESQview/X System Library. HELP.H is a file that defines error 
  217. return codes and prototypes for the Help interface routines - 
  218. this file should be included into your program code. The 
  219. DESQview/X System Library, LIBSYS.A, contains the Help 
  220. interface routines and should be linked in with your program - it 
  221. can be found in the \DJGPP\CONTRIB\DVX\LIB directory.
  222.  
  223. HELP.H is found in the DESQview/X INCLUDE subdirectory, with 
  224. djgpp it is \DJGPP\CONTRIB\DVX\INCLUDE.
  225.  
  226. The four Help interface routines are:
  227.  
  228. Help_initialize    Initialize the help interface
  229.  
  230. Help_get_sections  Get the names of the notebook's sections (the 
  231.                    names on the tabs)
  232.  
  233. Help_show          Display the notebook at a particular topic
  234.  
  235. Help_terminate     Terminate use of the help interface
  236.  
  237.  
  238. Typically a program will use the following sequence of calls:
  239.  
  240.  
  241. Help_initialize(...);
  242. :
  243. Help_get_sections(...);
  244. /* place section names on Help menu */
  245. :
  246. /* help requested! */
  247. Help_show(a_topic);
  248. :
  249. /* help requested! */
  250. Help_show(another_topic);
  251. :
  252. /* help requested! */
  253. Help_show(and_another_topic);
  254. :
  255. Help_terminate(...);
  256.  
  257. Note that there is no Help_unshow (or similar command) - a user 
  258. may close the help notebook at their discretion or leave it open. 
  259. Hence the notebook operates independently of the application. If 
  260. the user performs an operation in the application which generates 
  261. another Help_show(...) command and its notebook is already open, 
  262. then that notebook will appear (if iconified) and is updated to 
  263. the specified topic.
  264.  
  265.  
  266. How it Works
  267. ------------
  268. Understanding how the Help system operates is beneficial in 
  269. tracking down problems and using the Help system effectively.
  270.  
  271. The Help system consists of a Help engine running in its own 
  272. DESQview process. This Help engine can accept requests from 
  273. multiple applications concurrently and will create multiple 
  274. independent notebooks. Even though applications can make requests 
  275. to the Help engine directly, the help interface routines are 
  276. provided to simplify that process.
  277.  
  278. Requests are made to the Help engine using the DESQview mailbox 
  279. API. When the Help engine has completed the operation it will 
  280. return a status code to the sender also using the mailbox API.
  281.  
  282. Let us now examine what function each of the help interface 
  283. routines perform:
  284.  
  285.  
  286. Help_initialize
  287. ---------------
  288. When called, this routine sets up an account that contains 
  289. information that will be sent to the Help system every time a 
  290. request to the Help engine is made. At this point no 
  291. communication with the Help engine (if it is present) is 
  292. performed.
  293.  
  294.  
  295. Help_get_sections
  296. -----------------
  297. This function tries to locate the help file on disk (help files 
  298. are relative to the Help system's directory and not the 
  299. application's). Once the help file is located, the section names 
  300. (and their corresponding topics) are extracted and returned to 
  301. the calling application.
  302.  
  303. Note that no communication with the Help engine (if it is 
  304. present) is performed.
  305.  
  306.  
  307. Help_show
  308. ---------
  309. When called, Help_show checks to see if the Help engine is 
  310. already running. If it is not, Help_show starts the Help engine 
  311. and waits for it to initialize itself. If there are any problems, 
  312. Help_show will time out and return an error to the application.
  313.  
  314. Once the Help engine is running (or was already running in the 
  315. first place), Help_show sends a mail message request to the Help 
  316. engine. The Help engine performs the request and sends back a 
  317. status mail message to Help_show. If there are any problems, 
  318. Help_show will time out and return an error to the application.
  319.  
  320.  
  321. Help_terminate
  322. --------------
  323. This function sends a message to the Help engine informing it 
  324. that the connection to a particular notebook is being severed and 
  325. deallocates the account information from local storage.
  326.  
  327.  
  328. Help Callback
  329. -------------
  330. There are times when the help interface routines loop constantly 
  331. waiting for something to happen (for example, after starting the 
  332. Help engine and waiting for it to initialize itself, or after 
  333. sending it a message and waiting for a reply).
  334.  
  335. There can be instances when the help interface routines spend a 
  336. significant amount of time (a few seconds) in these loops 
  337. (especially when starting the Help engine).  During this time, if 
  338. a user uncovers or resizes one of the application's windows, the 
  339. window will remain blank until the interface routine exits the 
  340. busy-wait loop.
  341.  
  342. To counteract this, the application may specify a callback 
  343. routine that will be called whenever the help interface routines 
  344. pass through a loop.  This callback routine may perform useful 
  345. work such as checking and reacting to Expose or ConfigureNotify 
  346. events.
  347.  
  348. The callback routine MUST be of the form:
  349.  
  350. void helpcallback (void *user_arg);
  351.  
  352.  
  353. Help Routines
  354. -------------
  355. A description of each of the 4 interface routines now follows:
  356.  
  357. Help_initialize()
  358. *****************
  359.  
  360. Synopsis
  361. --------
  362. #include <help.h>
  363.  
  364. int Help_initialize (char *display_name, char *win_title, 
  365.                      char *file_name,int start_timeout, 
  366.                      int send_timeout, Help_callback callback, 
  367.                      void *user_arg, HelpID *id);
  368.  
  369. Description
  370. -----------
  371. Help_initialize is used to initialize the help interface routines 
  372. and must be called before any others. It returns a Help ID that 
  373. is used in subsequent calls to save the trouble of specifying the 
  374. same information (display name, help file name, etc) every time.  
  375. This Help id can be thought of as a logical connection to the 
  376. Help system.
  377.  
  378. If an application wishes to display several different notebook 
  379. files or use several different displays, Help_initialize must be 
  380. called separately for each instance - in each case, a different 
  381. Help id will be returned.
  382.  
  383. display_name, the display where the notebook should appear. If 
  384. this parameter is NULL, XDisplayName is used as the display name.
  385.  
  386. win_title, the window title of the notebook. If this parameter is 
  387. NULL, Help! is used.
  388.  
  389. file_name, the name of the help file to be used. NOTE: this name 
  390. should be specified relative to where the Help system 
  391. runs,normally the HELP subdirectory of the DESQview/X - 
  392. \DVX\HELP. If you store your help file in this directory (as is 
  393. recommended), then no path is required in the filename. If you 
  394. store your help file with your application, then pass a fully 
  395. qualified drive:\path\filenameso that the Help system may locate 
  396. the file.
  397.  
  398. start_timeout, the number of seconds that the help interface 
  399. should wait after starting the Help system (using the specified 
  400. .DVP) and the system initializing itself. If the interface times 
  401. out (after a reasonable number of seconds - 15 or so) a problem 
  402. has probably occurred.
  403.  
  404. send_timeout, the number of seconds that the help interface 
  405. should wait after sending a request to the Help system and 
  406. waiting for a reply. If the interface times out (after a 
  407. reasonable number of seconds - 10 or so) a problem has probably 
  408. occurred.
  409.  
  410. callback, the name of a Help callback function that is called 
  411. whenever the help interface is waiting for a reply from the Help 
  412. system. This callback routine can handle Expose/Configure Notify 
  413. events, for example. If this parameter is NULL, then no callback 
  414. will occur.
  415.  
  416. user_arg, an argument that is always passed to the specified 
  417. callback function.
  418.  
  419. id, <RETURNED> the Help id created for this notebook.
  420.  
  421.  
  422. Help_get_sections()
  423. *******************
  424.  
  425. Synopsis
  426. --------
  427. #include <help.h>
  428.  
  429. int Help_get_sections(HelpID id, int *ntabs, char**tabs[], 
  430.                       char**topics[]);
  431.  
  432. Description
  433. -----------
  434. Help_get_sections returns the number of sections and a list of 
  435. section names (the tabs appearing along the bottom of a help 
  436. notebook). These names may be used on a help menu, for example. 
  437. In addition, the corresponding topic names (for use with the 
  438. Help_show function) are also returned.
  439.  
  440. id, Help id (returned by Help_initialize).
  441.  
  442. ntabs, <RETURNED> the number of sections in the help file.
  443.  
  444. tabs, <RETURNED> a pointer to an array of character 
  445. pointers.These character pointers point to the section names of 
  446. the help file (the tabs that appear along the bottom of a 
  447. notebook). These section names were created with malloc() and may 
  448. be freed with free() when no longer required. In addition the 
  449. array of character pointers is also created with malloc() and may 
  450. also be freed with free();
  451.  
  452. topics, <RETURNED> a pointer to an array of character 
  453. pointers.These character pointers point to each section's 
  454. corresponding topic name in the help file. These topic names were 
  455. created with malloc() and may be freed with free() when no longer 
  456. required. In addition the array of character pointers is also 
  457. created with malloc() and may also be freed with free();
  458.  
  459.  
  460. Help_show()
  461. ***********
  462.  
  463. Synopsis
  464. --------
  465. #include <help.h>
  466.  
  467. int Help_show(HelpID id, char *topic);
  468.  
  469. Description
  470. -----------
  471. Help_show instructs the Help system to display a notebook at a 
  472. particular topic.  If a notebook for a particular file is already 
  473. open, the Help system will move the notebook to the foreground 
  474. and update its contents to the new topic.
  475.  
  476. id, Help id (returned by Help_initialize).
  477.  
  478. topic, the name of the topic to display.
  479.  
  480.  
  481. Help_terminate()
  482. ****************
  483.  
  484. Synopsis
  485. --------
  486. #include <help.h>
  487.  
  488. int Help_terminate(HelpID id);
  489.  
  490. Description
  491. -----------
  492. Help_terminate is used when your application has finished with a 
  493. particular notebook (or connection to the Help system).
  494.  
  495. id, Help id (returned by Help_initialize).
  496.  
  497.  
  498. Error Codes
  499. -----------
  500. All help interface routines can return an error code (they all 
  501. return an integer value).
  502.  
  503. These codes are:
  504.  
  505. H_OK                    Success
  506.  
  507. /* Codes returned from Help system to interface routines */
  508. PAD_NO_MEMORY           No memory to complete operation
  509. PAD_NO_FILE             Help file not found
  510. PAD_BAD_FILE            Bad help file
  511. PAD_NO_TOPIC            Topic not found
  512. PAD_BAD_CMD             Bad request command - contact QOS
  513. PAD_SERVER_NO_MEM       Server out of memory
  514. PAD_NO_CONNECT          Couldn't connect to Server
  515.                        (XOpenDisplay failed)
  516. PAD_BAD_VERSION         Mismatch between Help system and help
  517.                         interface version numbers
  518.  
  519. /* Codes returned from all help interface routines */
  520. H_BAD_ID                Help id is invalid
  521. H_NO_MEMORY             No memory to complete operation
  522.  
  523. /* Codes returned by Help_get_sections */
  524. H_NO_FILE               Help file not found
  525. H_BAD_FILE              Bad help file
  526. H_NO_TOPIC              Topic not found
  527. H_BAD_DVPFILE           Help .DVP file could not be found/read
  528. H_FNAME_TOO_LONG        Help filename is too long
  529.  
  530. /* Codes returned by Help_show */
  531. H_TIMEOUT               Timeout occurred starting/sending message
  532.                         to Help system
  533. H_SEND_ERROR            Error occurred sending message to Help
  534.                         system
  535. H_RECEIVE_ERROR         Error occurred reading message from Help
  536.                         system
  537. H_START_ERROR           Couldn't start Help system - .DVP
  538.                         couldn't be found, bad .DVP or
  539.                         out of memory.
  540.  
  541.  
  542. Example Program
  543. ---------------
  544. The QDDVX Toolkit contains an example program, HELPCALL, that 
  545. uses the help interface routines. This program is contained in 
  546. the \DJGPP\CONTRIB\DVX\QDECK\HELP directory.
  547.  
  548. HELPCALL illustrates how to use the help interface routines and 
  549. may be compiled using your C compiler.
  550.  
  551.  
  552. Using DISPHELP
  553. --------------
  554. Included with DESQview/X is a standalone version of the help 
  555. interface routines - DISPHELP.EXE. This program may be used from 
  556. the DOS command line or within a .DVP file to display a help 
  557. notebook. (Application Manager uses this program to display all 
  558. of the notebooks in the Help group.)
  559.  
  560. DISPHELP.EXE is found in your DESQview/X directory (normally 
  561. \DVX).
  562.  
  563. Note that if an error occurs, DISPHELP displays the error code 
  564. returned by the help interface routines - see the Error Codes 
  565. section for a description of each error code.
  566.  
  567. DISPHELP [-display displayname] [-pif pifname] [-spawn] [-file 
  568. filename] [-topic topicname] [-name window name] [-help]
  569.  
  570. DISPHELP accepts the following command line parameters:
  571.     -display | -d displayname  
  572.  
  573. displayname, the display the notebook is to appear on. Default: 
  574. your DISPLAY DOS variable, or :0 if not defined.
  575.  
  576.     -pif | -p pifname
  577.  
  578. pifname, the .DVP file to use to start the Help system. Default: 
  579. DVXHELP.DVP
  580.  
  581. -spawn | -s
  582.  
  583. This switch, when specified, instructs the Help system to spawn a 
  584. completely separate notebook, even if an open notebook is already 
  585. displaying the same help file.
  586.  
  587. -file | -f filename
  588.  
  589. filename, the help file to display. Default: DVXHELP.HLP
  590.  
  591. -topic | -t topicname
  592.  
  593. topicname, the topic to display. Default: contents
  594.  
  595. -name | -n window name
  596.  
  597. window name, the name of the notebook's window. Default: Help!
  598.  
  599. -help | -h | -?
  600.  
  601. Displays a brief reminder of DISPHELP's parameters. 
  602.  
  603.  
  604.  
  605.  
  606.  
  607.